CADOCommand Class

Defines a specific command that you intend to execute against a data source.

Include file: CADOCommand.inc (include CADODB.inc)

Methods and Properties

Remarks

Use a Command object to query a database and return records in a Recordset object, to execute a bulk operation, or to manipulate the structure of a database. Depending on the functionality of the provider, some Command collections, methods, or properties may generate an error when referenced.

With the collections, methods, and properties of a Command object, you can do the following:

• Define the executable text of the command (for example, an SQL statement) with the CommandText property. Alternatively, for command or query structures other than simple strings (for example, XML template queries) define the command with the CommandStream property.
• Optionally, indicate the command dialect used in the CommandText or CommandStream with the Dialect property.
• Define parameterized queries or stored-procedure arguments with Parameter objects and the Parameters collection.
• Indicate whether parameter names should be passed to the provider with the NamedParameters property.
• Execute a command and return a Recordset object if appropriate with the Execute method.
• Specify the type of command with the CommandType property prior to execution to optimize performance.
• Control whether the provider saves a prepared (or compiled) version of the command prior to execution with the Prepared property.
• Set the number of seconds that a provider will wait for a command to execute with the CommandTimeout property.
• Associate an open connection with a Command object by setting its ActiveConnection property.
• Set the Name property to identify the Command object as a method on the associated Connection object.
• Pass a Command object to the Source property of a Recordset in order to obtain data.
• Access provider-specific attributes with the Properties collection.

Note: To execute a query without using a Command object, pass a query string to the Execute method of a Connection object or to the Open method of a Recordset object. However, a Command object is required when you want to persist the command text and re-execute it, or use query parameters.

To create a Command object independently of a previously defined Connection object, set its ActiveConnection property to a valid connection string. ADO still creates a Connection object, but it doesn't assign that object to an object variable. However, if you are associating multiple Command objects with the same connection, you should explicitly create and open a Connection object; this assigns the Connection object to an object variable. Make sure the Connection object was opened successfully before you assign it to the Command object's ActiveConnection property, because assigning a closed Connection object causes an error. If you do not set the Command object's ActiveConnection property to this object variable, ADO creates a new Connection object for each Command object, even if you use the same connection string.

To execute a Command, simply call it by its Name property on the associated Connection object. The Command must have its ActiveConnection property set to the Connection object. If the Command has parameters, pass their values as arguments to the method.

If two or more Command objects are executed on the same connection and either Command object is a stored procedure with output parameters, an error occurs. To execute each Command object, use separate connections or disconnect all other Command objects from the connection.

CADOParameters Class

Contains all the Parameter objects of a Command object.

Include file: CADOParameters.inc (include CADODB.inc)

Methods and Properties

Remarks

A Command object has a Parameters collection made up of Parameter objects.

Using the Refresh method on a Command object's Parameters collection retrieves provider parameter information for the stored procedure or parameterized query specified in the Command object. Some providers do not support stored procedure calls or parameterized queries; calling the Refresh method on the Parameters collection when using such a provider will return an error.

If you have not defined your own Parameter objects and you access the Parameters collection before calling the Refresh method, ADO will automatically call the method and populate the collection for you.

You can minimize calls to the provider to improve performance if you know the properties of the parameters associated with the stored procedure or parameterized query you wish to call. Use the CreateParameter method to create Parameter objects with the appropriate property settings and use the Append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the provider for the parameter information. If you are writing to a provider that does not supply parameter information, you must manually populate the Parameters collection using this method to be able to use parameters at all. Use the Delete_ method to remove Parameter objects from the Parameters collection if necessary.

The objects in the Parameters collection of a Recordset go out of scope (therefore becoming unavailable) when the Recordset is closed.

CADOParameter Class

Represents a parameter or argument associated with a Command object based on a parameterized query or stored procedure.

Methods and Properties

Remarks

Many providers support parameterized commands. These are commands in which the desired action is defined once, but variables (or parameters) are used to alter some details of the command. For example, an SQL SELECT statement could use a parameter to define the matching criteria of a WHERE clause, and another to define the column name for a SORT BY clause.

Parameter objects represent parameters associated with parameterized queries, or the in/out arguments and the Return values of stored procedures. Depending on the functionality of the provider, some collections, methods, or properties of a Parameter object may not be available.

With the collections, methods, and properties of a Parameter object, you can do the following:

• Set or return the name of a parameter with the Name property.

• Set or return the value of a parameter with the Value property. Value is the default property of the Parameter object.

• Set or return parameter characteristics with the Attributes, Direction, Precision, NumericScale, Size, and Type_ properties.
• Pass long binary or character data to a parameter with the AppendChunk method.
• Access provider-specific attributes with the Properties collection.

If you know the names and properties of the parameters associated with the stored procedure or parameterized query you wish to call, you can use the CreateParameter method to create Parameter objects with the appropriate property settings and use the Append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the Refresh method on the Parameters collection to retrieve the parameter information from the provider, a potentially resource-intensive operation.

The Parameter object is not safe for scripting.

ActiveConnection (CADOCommand)

Determines the Connection object over which the specified Command object will execute.

PROPERTY ActiveConnection (BYREF vConn AS CVAR)
PROPERTY ActiveConnection (BYVAL pconn AS Afx_ADOConnection PTR)
PROPERTY ActiveConnection (BYREF pconn AS CAdoConnection)
PROPERTY ActiveConnection () AS Afx_ADOCOnnection PTR

Return value

An ADO Connection object reference. You must release it calling the Release method of the interface when no longer needed.

Remarks

If you attempt to call the Execute method on a Command object before setting this property to an open Connection object or valid connection string, an error occurs.

If a Connection object is assigned to the ActiveConnection property, the object must be opened. Assigning a closed Connection object causes an error.

Setting the ActiveConnection property to a null reference disassociates the Command object from the current Connection and causes the provider to release any associated resources on the data source. You can then associate the Command object with the same or another Connection object. Some providers allow you to change the property setting from one Connection to another, without having to first set the property to null.

If the Parameters collection of the Command object contains parameters supplied by the provider, the collection is cleared if you set the ActiveConnection property to null or to another Connection object. If you manually create Parameter objects and use them to fill the Parameters collection of the Command object, setting the ActiveConnection property to null or to another Connection object leaves the Parameters collection intact.

Closing the Connection object with which a Command object is associated sets the ActiveConnection property to null. Setting this property to a closed Connection object generates an error.

Example

' // Create a Connection object
DIM pConnection AS CAdoConnection
' // Create a Command object
DIM pCommand AS CAdoCommand
' // Open the connection
DIM cvConStr AS CVAR = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"
pConnection.Open cvConStr
' // Set the active connection
pCommand.ActiveConnection = pConnection

Cancel (CADOCommand)

Cancels execution of a pending, asynchronous method call.

FUNCTION Cancel() AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Use the Cancel method to terminate execution of an asynchronous method call (that is, a method invoked with the adAsyncConnect, adAsyncExecute, or adAsyncFetch option).

For a Command object, the last asynchronous call to the Execute method is terminated.

CommandStream (CADOCommand)

Sets or returns the stream used as the input for a Command object. The format for this stream is provider-specific, see your provider's documentation for details. This property is similar to the CommandText property, used to specify a string for the input of a Command.

POPERTY CommandStream () AS Afx_AdoStream
POPERTY CommandStream (BYVAL pStream AS Afx_AdoStream)

Return value

An Stream object reference.

Remarks

CommandStream and CommandText are mutually exclusive. When the user sets the CommandStream property, the CommandText property will be set to the empty string (""). If the user sets the CommandText property, the CommandStream property will be set to null.

The behaviors of the Command.Parameters.Refresh and Command.Prepare methods are defined by the provider. The values of parameters in a stream may not be refreshed.

The input stream is not available to other ADO objects that return the source of a Command. For example, if the Source property of a Recordset is set to a Command object that has a stream as its input, Recordset.Source continues to return the CommandText property, which contains an empty string (""), instead of the stream contents of the CommandStream property.

When using a command stream (as specified by CommandStream), the only valid CommandTypeEnum values for the CommandType property are adCmdText and adCmdUnknown. Any other value causes an error.

CommandText (CADOCommand)

Sets or returns an string value that contains a provider command, such as an SQL statement, a table name, a relative URL, or a stored procedure call. Default is "" (zero-length string).

PROPERTY CommandText () AS CBSTR
PROPERTY CommandText (BYVAL cbsText AS CBSTR)

Return value

A provider command, a table name, a relative URL, or a stored procedure call.

Remarks

Use the CommandText property to set or return the text of a command represented by a Command object. Usually this will be an SQL statement, but can also be any other type of command statement recognized by the provider, such as a stored procedure call. An SQL statement must be of the particular dialect or version supported by the provider's query processor.

If the Prepared property of the Command object is set to True and the Command object is bound to an open connection when you set the CommandText property, ADO prepares the query (that is, a compiled form of the query that is stored by the provider) when you call the Execute or Open methods.

Depending on the CommandType property setting, ADO may alter the CommandText property. You can read the CommandText property at any time to see the actual command text that ADO will use during execution.

Use the CommandText property to set or return a relative URL that specifies a resource, such as a file or directory. The resource is relative to a location specified explicitly by an absolute URL, or implicitly by an open Connection object.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Example

' // Create a Connection object
DIM pConnection AS CAdoConnection
' // Create a Command object
DIM pCommand AS CAdoCommand
' // Open the connection
DIM cvConStr AS CVAR = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"
pConnection.Open cvConStr
' // Set the active connection
pCommand.ActiveConnection = pConnection
' // Set the CommandText property
DIM cbsSqlStr AS CBSTR = "SELECT TOP 20 * FROM Authors ORDER BY Author"
pCommand.CommandText = cbsSqlStr

CommandTimeout (CADOCommand)

Sets or returns a Long value that indicates, in seconds, how long to wait for a command to execute. Default is 30.

PROPERTY CommandTimeout () AS LONG
PROPERTY CommandTimeout (BYVAL lTimeout AS LONG) 

Return value

Timeout value, in seconds.

Remarks

Use the CommandTimeout property on a Connection object or Command object to allow the cancellation of an Execute method call, due to delays from network traffic or heavy server use. If the interval set in the CommandTimeout property elapses before the command completes execution, an error occurs and ADO cancels the command. If you set the property to zero, ADO will wait indefinitely until the execution is complete. Make sure the provider and data source to which you are writing code support the CommandTimeout functionality.

The CommandTimeout setting on a Connection object has no effect on the CommandTimeout setting on a Command object on the same Connection; that is, the Command object's CommandTimeout property does not inherit the value of the Connection object's CommandTimeout value.

On a Connection object, the CommandTimeout property remains read/write after the Connection is opened.

CommandType (CADOCommand)

Sets or returns one or more CommandTypeEnum values.

Note: Do not use the CommandTypeEnum values of adCmdFile or adCmdTableDirect with CommandType. These values can only be used as options with the Open and Requery methods of a Recordset.

PROPERTY CommandType (BYVAL lCmdType AS CommandTypeEnum)
PROPERTY CommandType () AS CommandTypeEnum

Return value

A CommandTypeEnum value.

CommandTypeEnum

Remarks

Use the CommandType property to optimize evaluation of the CommandText property.

If the CommandType property value equals adCmdUnknown (the default value), you may experience diminished performance because ADO must make calls to the provider to determine if the CommandText property is an SQL statement, a stored procedure, or a table name. If you know what type of command you're using, setting the CommandType property instructs ADO to go directly to the relevant code. If the CommandType property does not match the type of command in the CommandText property, an error occurs when you call the Execute method.

CreateParameter (CADOCommand)

Creates a new Parameter object with the specified properties.

FUNCTION CreateParameter (BYREF cbsName AS CBSTR = "", BYVAL nType AS DataTypeEnum = 0, _
   BYVAL Direction AS ParameterDirectionEnum = adParamInput, BYVAL Size AS LONG = 0, _
   BYREF cvValue AS CVAR = TYPE<VARIANT>(VT_ERROR,0,0,0,DISP_E_PARAMNOTFOUND)) AS Afx_ADOParameter PTR

Return value

Reference to an ADO Parameter object.

ParameterDirectionEnum

Specifies whether the Parameter represents an input parameter, an output parameter, both an input and an output parameter, or the Return value from a stored procedure.

DataTypeEnum

Specifies the data type of a Field, Parameter, or Property. The corresponding OLE DB type indicator is shown in parentheses in the description column of the following table.

Remarks

Use the CreateParameter method to create a new Parameter object with a specified name, type, direction, size, and value. Any values you pass in the arguments are written to the corresponding Parameter properties.

This method does not automatically append the Parameter object to the Parameters collection of a Command object. This lets you set additional properties whose values ADO will validate when you append the Parameter object to the collection.

If you specify a variable-length data type in the nType argument, you must either pass a nSize argument or set the Size property of the Parameter object before appending it to the Parameters collection; otherwise, an error occurs.

If you specify a numeric data type (adNumeric or adDecimal) in the nType argument, then you must also set the NumericScale and Precision properties.

Dialect (CADOCommand)

Indicates the dialect of the CommandText or CommandStream properties. The dialect defines the syntax and general rules that the provider uses to parse the string or stream.

The Dialect property contains a valid GUID that represents the dialect of the command text or stream. The default value for this property is {C8B521FB-5CF3-11CE-ADE5-00AA0044773D}, which indicates that the provider should choose how to interpret the command text or stream.

PROPERTY Dialect (BYREF cbsDialect AS CBSTR)
PROPERTY Dialect () AS CBSTR

Return value

The string representation of a valid GUID that represents the dialect of the command text or stream.

Remarks

ADO does not query the provider when the user reads the value of this property; it returns a string representation of the value currently stored in the Command object.

When the user sets the Dialect property, ADO validates the GUID and raises an error if the value supplied is not a valid GUID. See the documentation for your provider to determine the GUID values supported by the Dialect property.

Execute (CADOCommand)

Executes the query, SQL statement, or stored procedure specified in the CommandText or CommandStream property.

FUNCTION Execute (BYVAL RecordsAffected AS LONG PTR = NULL, _
   BYREF cvParameters AS CVAR = TYPE<VARIANT>(VT_ERROR,0,0,0,DISP_E_PARAMNOTFOUND), _
   BYVAL Options AS LONG = adCmdUnspecified) AS Afx_ADORecordset PTR

Note: Use the ExecuteOptionEnum value adExecuteNoRecords to improve performance by minimizing internal processing. If adExecuteStream was specified, the options adAsyncFetch and adAsynchFetchNonBlocking are ignored. Do not use the CommandTypeEnum values of adCmdFile or adCmdTableDirect with Execute. These values can only be used as options with the Open and Requery methods of a Recordset.

CommandTypeEnum

ExecuteOptionEnum

Specifies how a command argument should be interpreted.

Return value

An ADO Recordset object reference.

Remarks

Using the Execute method on a Command object executes the query specified in the CommandText property or CommandStream property of the object.

Results are returned in a Recordset (by default) or as a stream of binary information. To obtain a binary stream, specify adExecuteStream in Options, then supply a stream by setting the "Output Stream" property. An ADO Stream object can be specified to receive the results, or another stream object such as the IIS Response object can be specified. If no stream was specified before calling Execute with adExecuteStream, an error occurs. The position of the stream on return from Execute is provider specific.

If the command is not intended to return results (for example, an SQL UPDATE query) the provider returns NULL as long as the option adExecuteNoRecords is specified; otherwise Execute returns a closed Recordset. Some application languages allow you to ignore this return value if no Recordset is desired.

Execute raises an error if the user specifies a value for CommandStream when the CommandType is adCmdStoredProc, adCmdTable, or adCmdTableDirect.

If the query has parameters, the current values for the Command object's parameters are used unless you override these with parameter values passed with the Execute call. You can override a subset of the parameters by omitting new values for some of the parameters when calling the Execute method. The order in which you specify the parameters is the same order in which the method passes them. For example, if there were four (or more) parameters and you wanted to pass new values for only the first and fourth parameters, you would pass an array of variants with the first and fourth elements holding the values and the second and third elements set to EMPTY as the Parameters argument.

Note: Output parameters will not return correct values when passed in the Parameters argument.

An ExecuteComplete event will be issued when this operation concludes.

Note: When issuing commands containing URLs, those using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Example

#include "Afx/CADODB/CADODB.inc"
using Afx

' // Open the connection
DIM pConnection AS CAdoConnection
pConnection.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=biblio.mdb"

' // Create a Command object
DIM pCommand AS CAdoCommand

' // Set the active connection
pCommand.ActiveConnection = pConnection

' // Set the CommandText property
pCommand.CommandText = "SELECT TOP 20 * FROM Authors ORDER BY Author"

' // Create the recordset by executing a query and attaching
' // the resulting recordset to an instance of the CAdoRecordset class.
DIM pRecordset AS CAdoRecordset
pRecordset.Attach(pCommand.Execute)

' // Parse the recordset
DO
   ' // While not at the end of the recordset...
   IF pRecordset.EOF THEN EXIT DO
   ' // Get the content of the "Author" column
   DIM cvRes AS CVAR = pRecordset.Collect("Author")
   PRINT cvRes
   ' // Fetch the next row
   IF pRecordset.MoveNext <> S_OK THEN EXIT DO
LOOP

GetErrorInfo (CADOCommand)

Returns information about ADO errors.

FUNCTION GetErrorInfo (BYVAL nError AS HRESULT = 0) AS CBSTR

Return value

A description of the error(s).

Name (CADOCommand)

Sets or returns an string value that indicates the name of a Command object.

PROPERTY Name () AS CBSTR
PROPERTY Name (BYREF cbsName AS CBSTR) 

Return value

The name of the Command object.

NamedParameters (CADOCommand)

Indicates whether parameter names should be passed to the provider.

PROPERTY NamedParameters () AS BOOLEAN
PROPERTY NamedParameters (BYVAL fNamedParameters AS BOOLEAN)

Return value

True or False.

Remarks

When this property is true, ADO passes the value of the Name property of each parameter in the Command's Parameter collection. The provider uses a parameter name to match parameters in the CommandText or CommandStream properties. If this property is false (the default), parameter names are ignored and the provider uses the order of parameters to match values to parameters in the CommandText or CommandStream properties.

Parameters (CADOCommand)

Returns a reference to the Parameters collection.

PROPERTY Parameters () AS Afx_ADOParameters

Return value

A reference to the Parameters collection.

Prepared (CADOCommand)

Sets or returns a Boolean value that, if set to True, indicates that the command should be prepared.

PROPERTY Prepared () AS BOOLEAN
PROPERTY Prepared (BYVAL fPrepared AS BOOLEAN)

Return value

True or False.

Remarks

Use the Prepared property to have the provider save a prepared (or compiled) version of the query specified in the CommandText property before a Command object's first execution. This may slow a command's first execution, but once the provider compiles a command, the provider will use the compiled version of the command for any subsequent executions, which will result in improved performance.

If the property is False, the provider will execute the Command object directly without creating a compiled version.

If the provider does not support command preparation, it may return an error as soon as this property is set to True. If it does not return an error, it simply ignores the request to prepare the command and sets the Prepared property to False.

Properties (CADOCommand)

Returns a reference to the Properties collection.

PROPERTY Properties () AS Afx_ADOProperties

Return value

A reference to the Properties collection.

State (CADOCommand)

Indicates if the Command object is open or closed.

PROPERTY State () AS LONG

Return value

Returns a Long value that can be an ObjectStateEnum value. The default value is adStateClosed.

ObjectStateEnum

Specifies whether the Open method of a Connection object should return after (synchronously) or before (asynchronously) the connection is established.

Append (CADOParameters)

Appends an object to the Parameters collection.

FUNCTION Append (BYVAL pObject AS IDispatch PTR) AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

You must set the Type_ property of a Parameter object before appending it to the Parameters collection. If you select a variable-length data type, you must also set the Size property to a value greater than zero.

Describing parameters yourself minimizes calls to the provider and consequently improves performance when using stored procedures or parameterized queries. However, you must know the properties of the parameters associated with the stored procedure or parameterized query that you want to call.

Use the CreateParameter method to create Parameter objects with the appropriate property settings and use the Append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the provider for the parameter information. If you are writing to a provider that does not supply parameter information, you must use this method to manually populate the Parameters collection in order to use parameters at all.

Count (CADOParameters)

Retrieves the number of objects of the Parameters collection.

PROPERTY Count () AS LONG

Return value

The number of objects in the Parameters collection.

Remarks

Because numbering for members of a collection begins with zero, you should always code loops starting with the zero member and ending with the value of the Count property minus 1.

If the Count property is zero, there are no objects in the collection.

Delete_ (CADOParameters)

Deletes an object from the Parameters collection.

FUNCTION Delete_ (BYREF cvIndex AS CVAR) AS HRESULT

Return value

S_OK (0) or am HRESULT code.

Remarks

Using the Delete_ method on a collection lets you remove one of the objects in the collection. This method is available only on the Parameters collection of a Command object. You must use the Parameter object's Name property or its collection index when calling the Delete_ method—an object variable is not a valid argument.

Item (CADOParameters)

Indicates a specific member of the Parameters collection, by name or ordinal number.

PROPERTY Item (BYREF cvIndex AS CVAR) AS Afx_ADOParameter PTR

Return value

An ADO Parameter object reference.

Remarks

If Item cannot find an object in the collection corresponding to the Index argument, an error occurs.

Refresh (CADOParameters)

Refreshes the contents of the Parameters collection.

FUNCTION Refresh () AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Using the Refresh method on a Command object's Parameters collection retrieves provider-side parameter information for the stored procedure or parameterized query specified in the Command object. The collection will be empty for providers that do not support stored procedure calls or parameterized queries.

You should set the ActiveConnection property of the Command object to a valid Connection object, the CommandText property to a valid command, and the CommandType property to adCmdStoredProc before calling the Refresh method.

If you access the Parameters collection before calling the Refresh method, ADO will automatically call the method and populate the collection for you.

Note: If you use the Refresh method to obtain parameter information from the provider and it returns one or more variable-length data type Parameter objects, ADO may allocate memory for the parameters based on their maximum potential size, which will cause an error during execution. You should explicitly set the Size property for these parameters before calling the Execute method to prevent errors.

AppendChunk (CADOParameter)

Appends data to a Parameter object.

FUNCTION AppendChunk (BYREF cvData AS CVAR) AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Use the AppendChunk method on a Parameter object to fill it with long binary or character data. In situations where system memory is limited, you can use the AppendChunk method to manipulate long values in portions rather than in their entirety.

If the adParamLong bit in the Attributes property of a Parameter object is set to true, you can use the AppendChunk method for that parameter.

The first AppendChunk call on a Parameter object writes data to the parameter, overwriting any existing data. Subsequent AppendChunk calls on a Parameter object add to existing parameter data. An AppendChunk call that passes a null value discards all of the parameter data.

Attach (CADOParameter)

Attaches a reference to an Parameter object to the class.

SUB Attach (BYVAL pParameter AS Afx_ADOParameter PTR, BYVAL fAddRef AS BOOLEAN = FALSE)

Attributes (CADOParameter)

Indicates one or more characteristics of an object.

For a Parameter object, the Attributes property is read/write, and its value can be the sum of any one or more ParameterAttributesEnum values. The default is adParamSigned.

PROPERTY Attributes () AS LONG
PROPERTY Attributes (BYVAL lAttr AS LONG)

Return value

One or more ParameterAttributesEnum values.

ParameterAttributesEnum

Specifies the attributes of a Parameter object.

Remarks

For a Parameter object, the Attributes property is read/write, and its value can be the sum of any one or more ParameterAttributesEnum values. The default is adParamSigned.

Direction (CADOParameter)

Indicates whether the Parameter represents an input parameter, an output parameter, an input and an output parameter, or if the parameter is the return value from a stored procedure.

Sets or returns a ParameterDirectionEnum value.

PROPERTY Direction () AS ParameterDirectionEnum
PROPERTY Direction (BYVAL lParmDirection AS ParameterDirectionEnum)

Return value

One or more ParameterDirectionEnum values.

ParameterDirectionEnum

Specifies whether the Parameter represents an input parameter, an output parameter, both an input and an output parameter, or the return value from a stored procedure.

Remarks

Use the Direction property to specify how a parameter is passed to or from a procedure. The Direction property is read/write; this allows you to work with providers that don't return this information or to set this information when you don't want ADO to make an extra call to the provider to retrieve parameter information.

Not all providers can determine the direction of parameters in their stored procedures. In these cases, you must set the Direction property before you execute the query.

Name (CADOParameter)

Sets or returns an string value that indicates the name of a Parameter object.

PROPERTY Name () AS CBSTR
PROPERTY Name (BYVAL cbsName AS CBSTR)

Return value

The name of the **Parameter" object.

Remarks

For Parameter objects not yet appended to the Parameters collection, the Name property is read/write. For appended Parameter objects and all other objects, the Name property is read-only. Names do not have to be unique within a collection.

NumericScale (CADOParameter)

Indicates the scale of numeric values in a Parameter object.

Sets or returns a Byte value that indicates the number of decimal places to which numeric values will be resolved.

PROPERTY NumericScale () AS BYTE
PROPERTY NumericScale (BYVAL bScale AS BYTE)

Return value

The number of decimal places.

Remarks

Use the umericScale property to determine how many digits to the right of the decimal point will be used to represent values for a numeric Parameter object.

For Parameter objects, the NumericScale property is read/write.

Precision (CADOParameter)

Indicates the degree of precision for numeric values in a Parameter object.

Sets or returns a Byte value that indicates the maximum number of digits used to represent values.

PROPERTY Precision () AS BYTE
PROPERTY Precision (BYVAL bPrecision AS BYTE)

Return value

The degress of precision.

Remarks

Use the Precision property to determine the maximum number of digits used to represent values for a numeric Parameter object.

Properties (CADOParameter)

Returns a reference to the Properties collection.

PROPERTY Properties () AS Afx_ADOProperties

Return value

A Properties object reference.

Size (CADOParameter)

Sets or returns a Long value that indicates the maximum size in bytes or characters of a value in a Parameter object.

PROPERTY Size () AS LONG
PROPERTY Size (BYVAL lSize AS LONG)

Return value

The maximum size.

Remarks

Use the Size property to determine the maximum size for values written to or read from the Value property of a Parameter object.

If you specify a variable-length data type for a Parameter object (for example, any string type, such as adVarChar), you must set the object's Size property before appending it to the Parameters collection; otherwise, an error occurs.

If you have already appended the Parameter object to the Parameters collection of a Command object and you change its type to a variable-length data type, you must set the Parameter object's Size property before executing the Command object; otherwise, an error occurs.

If you use the Refresh method to obtain parameter information from the provider and it returns one or more variable-length data type Parameter objects, ADO may allocate memory for the parameters based on their maximum potential size, which could cause an error during execution. To prevent an error, you should explicitly set the Size property for these parameters before executing the command.

The Size property is read/write.

Type_ (CADOParameter)

Indicates the operational type or data type of a Parameter object.

PROPERTY Type_ () AS DataTypeEnum

Return value

A DataTypeEnum value.

DataTypeEnum

Specifies the data type of a Field, Parameter, or Property. The corresponding OLE DB type indicator is shown in parentheses in the description column of the following table.

Value (CADOParameter)

Indicates the value assigned to a Parameter object.

PROPERTY Value () AS CVAR
PROPERTY Value (BYREF cvValue AS CVAR)

Return value

The value of the Parameter object.

Remarks

Use the Value property to set or return parameter values with Parameter objects.

ADO allows setting and returning long binary data with the Value property.

For Parameter objects, ADO reads the Value property only once from the provider. If a command contains a Parameter whose Value property is empty, and you create a Recordset from the command, ensure that you first close the Recordset before retrieving the Value property. Otherwise, for some providers, the Value property may be empty, and won't contain the correct value.